------------------------------------ README FILE for Dspot(Nag) Version 1 ------------------------------------ --> Currently available on Intel and SGI platforms <-- Special thanks to Marvin Landis for compiling the SGI version. ================= Table Of Contents ================= Description Installation Dependencies Tested On... Known Limitations Bug Reports How to Purchase ----------- Description ----------- Overview -------- Dspot is a layout/animation displacement plugin, a procedural displacement handler/interface in LW SDK terms. Once installed, it appears as a "Disp Map Plug-in" in Layout's Objects panel. It acts something like a displacement effector, altering objects' geometry based on a number of factors specified by the user. Dspot is a silly name that's sort of an abbreviation for "displacement spot", as early tests just used a null item as the effector. The Dspot plugin is copyright 1997 by D.J. Hudek. Dspots can be used for a variety of "fun" effects. Put a radial style attractor dspot in the mouth of a hand-held vacuum and suck in a buick. Put a parallel style repeller in the vicinity and fly a bird into a plate glass window (smooshing flat as it hits). Use a parallel style attractor to allow a monster to emerge from the ground as the attraction is lessened, or a giant cartoon electro-magnet to deform and attract the evil robot, or use a sinusoidal modifier on a radial dspot and allow a tophat to beat like a heart, or use a radial style dspot as a "force-field" around a hero object and it can push/deform other objects out of the way as it barges its way along, or create a small hole in a high altitude jet and use an attractor dspot to squirt people and other items out of it, or use several different styles with differing modifiers scattered about in space and deform a ship as it flies through, or or or... well, there are many many combinations of parameters each with different effects... it's fun to experiment and play around. :-) Dspots act on an object-by-object basis, applied via Layout's Objects Panel, under the "Disp Map Plug-ins" widget. Any object, light, or camera may act as a Dspot for any object or objects. An object may have multiple Dspots which affect it. For each, one has control over a number of parameters which determine the amount of displacement a dspot will apply to an object at any point in time: * Item to act as a Dspot for this object * Attract or Repel * Various displacement styles (radial, plus 4 types of parallel) * InnerRadius (may be animated) * OuterRadius (may be animated) * Raw displacement to apply * Displacement strength falloff (none, 1/d, 1/d**2, d) * Strength modifier (none, sinusoid with specified period and phase, or animatable via control item) If a particular point on the object is further away than the outside radius, no displacement is applied. If it is between the outer and inner radius, the displacement is determined by "(raw displacement) * (strength falloff) * (modifier)" If a point is closer than the inner radius, it is pushed back (except for one of the parallel styles, points may not invade a dspot's inner radius). The inner radius, the outer radius, and the strength modifier (and therefore the displacement to apply) may all be animated. Experiment with the settings and have fun. Invocation ---------- After installation of the plugin, Dspots can be invoked for an object by means of the "Disp Plug-ins" option in the Objects Panel. Once selected, the user interface is accessed via the associated "Options" button. User Interface -------------- The first menu presented gives one the option of creating a new Dspot, modifying an existing Dspot (if any have been created), or Deleting a Dspot (again, only makes sense if some have been created). The bottom half of the menu provides a popup list of all the Dspots currently created for the object (if any), from which to choose for the modify or delete action. [[ Create A New Dspot ]] The first time this is invoked for an object, a funny question will appear at the top (see Known Limitations, below). The SDK isn't too good about always accurately letting the software know which object is the subject of interest, so the first item may claim "amnesia" and ask you to supply the name of the object for which you intend to add Dspots. An odd workaround. This should only happen the first time you create a dspot for the object. Most of the remaining items are self-explanatory. The next widget asks you to specify which object, light or camara will be acting as a Dspot with the set of parameters you are about to supply. The next widget asks whether the Dspot should Attract or Repel. The next three widgets concern the inner and outer radii of the Dspot. They define space in which the Dspot may exert displacement upon the object, as described above in the overview. If one so chooses, the radii values may be changed over time by use of a control item (which will specified at the bottom of the menu). If used, the inner radius will be multiplied by the control item's X channel value, while the outer radius will be multiplied by the item's Y channel value. Of course, one should keep the inner radius value less than the outer radius. The default is to use static radii values and not use the control item for dynamic scaling. The next widget asks for the raw displacement to apply to points when they are within range of the Dspot. This raw value will be altered based upon the strength falloff and strength modifier values which are specified below. The basic equation for the displacement to apply is rawDisplacement x falloff x modifier. The next widget asks for what style of displacement you desire. There are 5 options: Radial Parallel with X constrained Parallel with Y constrained Parallel with Z constrained Parallel with no contraints The Radial style applies a radial displacement (imagine a black hole for attractors, or an expanding bubble for repellers). The displacement radiates in/out evenly from the center pivot point of the Dspot item. Points on the object will be displaced along different normals; each along a normal from the particular point to the Dspot pivot point. The inner radius of the Dspot is a no-man's-land. A point is not allowed within the inner radius and will always be displaced outside of it. The Parallel options apply displacement to all points using a single common normal... from the object's pivot point to the Dspot's pivot point. While the Radial displacement causes the object to shrink or grow, the parallel tends to keep the objects shape (of course, it will stretch or compress depending on the other parameters, but it doesn't shrink down to a tiny point as can happen with radial displacement). The first three styles are concerned with actions related to the inner radius. They allow one to set up imaginary parallel planes related to the inner radius between which points are not allowed (imagine two large plate glass windows, spaced on either side of the Dspot pivot point an innerRadius away, and aligned on the X, Y, or Z planes (as specified). Points may be displaced up to the planes, but not between them). The last Parallel option does not use the imaginary plane constraint, points may be displaced within the inner radius. The next widget in the menu asks about displacement strength falloff. Choices are : Constant (no falloff) 1 / Distance 1 / Distance**2 Distance - InnerRadius The first option specifies no strength falloff, the next two specify that the strength is generally inversely proportional to distance or distance squared, and the last one specifies that the strength is generally proportional to the distance (they are actually scaled by the inner to outer distance). The next widget allows one to specify a further strength modifier. Choices are: None Sinusoidal Control Item None means no further modifications. Sinusoidal indicates a sine modification, using the period and phase specified in the next two widgets. Control Item indicates that the Z Channel value of the control item (specified at the bottom of the menu, also used to control the inner/outer radii with its X and Y channels), will be used to further modify the displacement. As implied by the sinusoidal option (and certainly available to the control item), the Dspot attraction or repulsion may be reversed over time... a negative displacement while attracting is equivalent to a positive displacement while repelling and vice versa. The next two widgets are only used if the sinusoidal modifier was selected. They allow one to specify the period (in seconds) and phase (in radians) for the modifying sine wave. The final widget is only used if one wants to animate the inner/outer radii and/or the strength modifications. The X channel values of the specified item may be used to alter the inner radius, the Y channel value may be used to modify the outer radius, and the Z channel value may be used to modify the displacement strength. The control item allows one fairly arbitrary control of the Dspot behaviour. [[ Modify An Existing Dspot ]] This action allows one to modify the Dspot selected in the main menu. Upon invocation, it will bring up a menu that is almost identical to that used by Create New, except for the fact that the "amnesia" related question (what object am I anyway?) is always present (unlike the Create New Dspot when it is only present the first time a Dspot is added to an item). This will come in handy if one alters a scene such that Lightwave changes the object names and IDs on us (see Known Limitations below). The remaining widgets are identical to those described above in the Create New section. [[ Delete A Dspot ]] This action deletes the Dspot selected in the main menu. ------------ Installation ------------ If you are reading this, presumably you knew to unzip the downloaded file :-) After unzipping, there should be two new files: READMEDSPOT1.txt (this file) and either DspotNagV1.p (the plugin if you downloaded the Intel version) or sgiDspotNagV1.p (the plugin if you downloaded the SGI version) Simply move or copy the plugin file to whereever you keep your Layout plugins: On Intel Platform, typically DRIVE:\newtek\plugins\layout On SGI Platform, typically /usr/lightwave/plugins/layout Fire up Lighwave(Layout) and use Options/Add Plug-ins to add the plugin. If you do not already have the standard lwpanels.p added, be sure to do so before first activating Dspot. (If you so desire, you could also have edited the layout config file directly, but using the Add Plugin feature is easier and less prone to typing errors :-) ) Once Dspot has been added, you should see it as an option in the Object Panel/Disp Map Plug-ins list. ------------ Dependencies ------------ lwpanels.p Dspot relies on the services provided by the Lwpanels.p plugin. It must be added to Layout before this plugin will work. ------------ Tested On... ------------ Lightwave 5.0m on an Intel platform - Windows NT Workstation 4.0 on a Dual PII system Lightwave 5.0 on an Indigo 2 (IRIX 6.2) and an O2 (IRIX 6.3) Tested using relatively simple scenes, using a representative sample of the various options. The version of Lwpanels.p used in testing on the Intel platform was dated 6/29/96 and came with the vanilla lightwave installation (version 5.0m). This plugin should work with Lightwave version 5.5 as well. ----------------- Known Limitations ----------------- There are a few oddities imposed by the LW SDK. If the SDK changes in the future, these may be reduced/removed. The main oddities have to do with object naming and IDs. We don't always get the correct IDs when we expect them, and both IDs and names fluctuate depending on how the user manipulates the scene elements, so in some menus the user is requested to supply the correct object name, from which we can derive its current ID. After creating clones of an object which used Dspots, one must open the Modify Dspot menu for each and supply them with their current name. Depending on if the base object had already been cloned before or not, its name may have changed and again, the Modify Dspot menu should be used to supply the new name. When multiple copies of an object are present in a scene and then ones in the middle deleted (e.g., cows 1 to 6 originally, then change your mind and delete cow(3)), some names and ids are changed, so again, one may need to use the Modify Dspot menu to supply the correct name ** SPECIAL ---> ONLY FOR LIMITED TRIAL VERSION: This version of the plugin is intended only for a limited time trial use, to allow the user to determine if it's helpful or not. If it proves useful, the user is expected to purchase Dspots (see below). The nagging trial version has some artificial limitations. First, it will not save or load Dspot to/from the scene file. Second, it will only apply Dspot displacement for frames 1 to 30. Finally, the Modify menu will only accept changes for up to 10 times; after that, one must delete and create new to effect modifications, and it will nag you about purchasing the product if you try the modify option. Of course, these limitations apply only to this trial version; the actual product will save and load, displace past frame 30, and let you modify to your heart's content. :-) ----------- Bug Reports ----------- I tried to test a representative sample of the possible combinations, but some bugs have probably slipped through. If you'd care to submit any bug reports, they can be mailed to my aol account: hudeks@aol.com (the ultranet account is not checked as frequently). --------------- How to Purchase --------------- If you've used this version and don't find it to be useful, sorry, but thanks for giving it a test drive. :-) I may have others in the future that will prove more satisfactory. If it does prove helpful to you, please register and purchase it. The introductory purchase price is $50 and may be sent (check or money order) to the following address: D.J. Hudek 17 Bruce St. Grafton, MA 01519 If you include your email address, a non-crippled/non-nagging version of Dspot.p will be sent in return. Be sure to specify which platform you will run it on (Intel or SGI). I can't imagine that anyone who would use this doesn't have an email address (???) but if so, we could probably arrange a floppy mailing for a nominal extra fee. Thanks, d.j.hudek